feat: support needs[].parallel.matrix and matrix expressions - #1848

Summary

Adds support for two related GitLab CI features for parallel-matrix jobs:

1. Static needs[].parallel.matrix selectors — pick specific producer permutations to depend on (closes Implement needs[].parallel.matrix #843). Shipped upstream in GitLab 16.3 (gitlab-org/gitlab!118839).

2. Matrix expressions $[[ matrix.IDENTIFIER ]] inside selectors — resolved per consumer permutation, enabling 1:1 dependency mapping across stages. Shipped upstream as Beta in GitLab 18.6, GA in 18.8 (gitlab-org/gitlab!205247 + flag removal in !209773).

The original schema already permits needs[].parallel (refs parallel_matrix), so no schema patch is needed.

What works

Layer 1 — static selectors

• Full selectors, e.g. parallel.matrix: [{NAME: foo}] selects only build-job: [foo]
• Array-valued selectors expand to a cartesian product, e.g. [{NAME: [foo, bar]}]
• Multi-key entries
• optional: true skips silently when the selector matches zero permutations

Layer 2 — matrix expressions

• Bare canonical form PROVIDER: $[[ matrix.PROVIDER ]] (matches the example in gitlab-org/gitlab#423553)
• Array-wrapped form PROVIDER: ['$[[ matrix.PROVIDER ]]']
• Multiple expressions concatenated in one string, e.g. TAG: build-$[[ matrix.OS ]]-$[[ matrix.STACK ]]
• Identifiers with letters, digits, underscore, and hyphen (matches upstream's [a-zA-Z0-9_-]+ regex in MatrixInterpolator)
• Whitespace variations inside $[[ ... ]]
• Mixed entries (some keys literal, some expression-based)

Errors

• Producer without parallel:matrix (including plain parallel: <int>)
• Selector matching zero producer permutations on a non-optional need
• $[[ matrix.X ]] in a consumer that is not parallel-matrix
• $[[ matrix.X ]] referencing an identifier the consumer's matrix doesn't define — wording mirrors upstream's 'X' does not exist in matrix configuration for log grep parity

Tests

Six new fixtures under tests/test-cases/, 18 integration tests total:

The matrix-expressions fixtures mirror the cases in upstream's spec/lib/gitlab/ci/config/interpolation/matrix_interpolator_spec.rb adapted to gitlab-ci-local's integration-test infrastructure.

Behavior note: partial selectors

The original #254821 issue description marked partial selectors (selector mentions only a subset of the producer's matrix keys) as "out of scope". This implementation supports them: a selector key list is treated as a constraint, with the producer's unmentioned keys free to take any value. This is also the behavior implied by upstream's matrix-expression test fixtures (which show partial-key shapes working) and is the more useful pattern when combined with $[[ matrix.X ]] substitution.

Happy to tighten this if you'd prefer strict full-selector semantics — let me know.

Out of scope (follow-ups if requested)

• Interaction with spec: headers / inputs expressions (separate code path that already lives in this project)
• Numeric matrix values are accepted by String(v) coercion but lack an explicit fixture
• extends: propagation of needs[].parallel.matrix (likely works via existing deepExtend, untested)

References

• Issues: #843, gitlab-org/gitlab#254821, gitlab-org/gitlab#423553, gitlab-org/gitlab#581803
• Upstream MRs: gitlab-org/gitlab!118839, gitlab-org/gitlab!205247
• Docs: needs:parallel:matrix, matrix expressions

Test plan

• bun run typecheck
• bun run lint
• bunx vitest run tests/test-cases/needs-parallel-matrix-*
• CI green (already verified via internal fork PR before opening this one)

Acknowledgment

This PR was implemented with assistance from Claude (Anthropic) as a pair-programming tool. The implementation was audited against upstream gitlab-org/gitlab MRs and test files (notably !118839 and !205247) to ensure behavior parity with GitLab Runner's own logic. All code and tests were reviewed by me before pushing; CI on the internal fork PR confirmed the full vitest suite and four Node/Bun smoke matrix variants pass on Linux. Co-authorship is preserved in the commit trailer.

Summary by cubic

Adds support for needs[].parallel.matrix selectors and $[[ matrix.X ]] expressions. This enables precise, 1:1 dependency mapping across parallel.matrix jobs and ensures artifacts flow only from matched permutations.

• New Features
  • Static selectors: choose specific producer permutations. Supports arrays (cartesian), multi-key and partial selectors, and optional: true for zero matches.
  • Matrix expressions: resolve $[[ matrix.IDENTIFIER ]] per consumer permutation. Supports array-wrapped values, multiple expressions in one string, hyphenated identifiers, and whitespace variations.
  • Validation: errors if producer is not parallel:matrix (including parallel:), if a non-optional selector matches nothing, if a non-parallel consumer uses expressions, or if an expression references an unknown identifier.
  • Artifacts: consumers pull artifacts only from matched producer permutations.

^{Written for commit 772dfaf. Summary will update on new commits.}